Developer Documentation

QuickTime 4 API Documentation

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Functions

ImageCodecExtractAndCombineFields

Performs field operations on video data. It allows fields from two separate images, compressed in the same format, to be combined in to a new compressed frame. Typically the operation results in an image of identical quality to the source images. Fields of a single image may also be duplicated or reversed by this function.

pascal ComponentResult ImageCodecExtractAndCombineFields (
                     ComponentInstance ci,
                     long fieldFlags,
                     void *data1,
                     long dataSize1,
                     ImageDescriptionHandle desc1,
                     void *data2,
                     long dataSize2,
                     ImageDescriptionHandle desc2,
                     void *outputData,
                     long *outDataSize,
                     ImageDescriptionHandle descOut);
ci
Specifies the image compressor component for the request.

fieldFlags
Flags specifying the operation to be performed. A correctly formed request will specify two input fields, mapping one to the odd output field and the other to the even output field. The following flags are defined:

evenField1ToEvenFieldOut
Maps the even field specified by the data1 parameter to the even output field.

evenField1ToOddFieldOut
Maps the even field specified by the data1 parameter to the odd output field.

oddField1ToEvenFieldOut
Maps the odd field specified by the data1 parameter to the even output field.

oddField1ToOddFieldOut
Maps the odd field specified by the data1 parameter to the odd output field.

evenField2ToEvenFieldOut
Maps the even field specified by the data2 parameter to the even output field.

evenField2ToOddFieldOut
Maps the even field specified by the data2 parameter to the odd output field.

oddField2ToEvenFieldOut
Maps the odd field specified by the data2 parameter to the even output field.

oddField2ToOddFieldOut
Maps the odd field specified by the data2 parameter to the odd output field.

data1
A pointer to a buffer containing the compressed image data for the first input field.

dataSize1
Specifies the size of the data1 buffer.

desc1
An image description structure describing the format and characteristics of the data in the data1 buffer.

data2
A pointer to a buffer containing the compressed image data for the second input field. Set to nil if the requested operation uses only one input frame.

dataSize2
Specifies the size of the data2 buffer. Set to 0 if the requested operation uses only one input frame.

desc2
An image description structure describing the format and characteristics of the data in the data2 buffer. Set to nil if the requested operation uses only one input frame.

outputData
A pointer to a buffer to receive the resulting frame.

outDataSize
On output this parameter returns the actual size of the new compressed image data.

descOut
Specifies the desired format of the resulting frames. Typically this is the same format specified by the desc1 and desc2 parameters.

DISCUSSION

This codec routine implements the functionality of the ImageFieldSequenceExtractCombine function described in Chapter 3, "Image Compression Manager." If your codec is capable of separately compressing both fields of a video frame, you should incorporate support for this function.

Your codec must ensure that it understands the image formats specified by desc1 and desc2 parameters, as these may not be the same as the codec's native image format. The image format specified by the descOut parameter will be the same as the codec's native image format.

The component selector for this function is:

kImageCodecExtractAndCombineFieldsSelect    = 0x0015

ImageCodecFlush

Empties a image decompressor component's input queue of pending scheduled frames.

pascal ComponentResult ImageCodecFlush(
                     ComponentInstance ci);
ci
Specifies the image decompressor component for the request.

DISCUSSION

Your component receives the ImageCodecFlush function whenever the Image Compression Manager needs to cancel the display of all scheduled frames.

Your decompressor should empty its queue of scheduled asynchronous decompression requests. For each request, your component must call the ICMDecompressComplete function. Be sure to set the err parameter to -1, indicating that the request was canceled. Also, you must set both the codecCompletionSource and codecCompletionDest flags to 1. Only decompressor components that support scheduled asynchronous decompression receive this call.

Special Considerations

Your component's ImageCodecFlush function may be called at interrupt time.

ImageCodecSetTimeCode

Sets the timecode for the next frame that is to be decompressed.

pascal OSErr ImageCodecSetTimeCode (
                     ComponentInstance ci,
                     void *timeCodeFormat,
                     void *timeCodeTime);
ci
Specifies the image decompressor component for the request.

timeCodeFormat
Contains a pointer to a timecode definition structure. This structure contains the timecode definition information for the next frame to be decompressed.

timeCodeTime
Contains a pointer to a timecode record structure. This structure contains the time value for the next frame in the current sequence.

DISCUSSION

Your component receives ImageCodecSetTimeCode function whenever an application calls the Image Compression Manager's SetDSequenceTimeCode function. That function allows an application to set the timecode for a frame that is to be decompressed.

The timecode information you receive applies to the next frame to be decompressed and is provided to the decompressor in the ImageCodecBandDecompress function.

ImageCodecIsImageDescriptionEquivalent

Compares image descriptions.

pascal ComponentResult ImageCodecIsImageDescriptionEquivalent (
                     ComponentInstance ci,
                     ImageDescriptionHandle newDesc,
                     Boolean *equivalent);
ci
Specifies the image compressor component for the request.

newDesc
Contains a handle to the image description structure that describes the compressed image.

equivalent
Contains a pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the image description currently in use by the image sequence, this value is set to true . If the ImageDescriptionHandle is not equivalent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to false .

DISCUSSION

Your component receives the ImageCodecIsImageDescriptionEquivalent request whenever an application calls the Image Compression Manager's CDSequenceEquivalentImageDescription function (page 211) . Implementing this function can significantly improve playback of edited video sequences using your codec. For example, if two sequences are compressed at different quality levels and are edited together they will have different image descriptions because their quality values will be different. This will force QuickTime to use two separate decompressor instances to display the images. By implementing this function your decompressor can tell QuickTime that differences in quality levels don't require separate decompressors. This saves memory and time, thus improving performance.

SPECIAL CONSIDERATIONS

The current image description is not passed in this function because the Image Compression Manager assumes the codec has already made copies of all relevant data fields from the current image description during the ImageCodecPreDecompress call.

ImageCodecNewMemory

Requests codec-allocated memory. Some hardware codecs may have on-board memory that can be used to store compressed and/or decompressed data. ImageCodecNewMemory makes this memory available for use by clients of the codec. Some software codecs may be able to optimize thier performance by having more control over memory allocation. ImageCodecNewMemory makes this control available.

pascal ComponentResult ImageCodecNewMemory (
                     ComponentInstance ci,
                     Ptr *data,
                     Size dataSize,
                     long dataUse,
                     ICMMemoryDisposedUPP memoryGoneProc,
                     void *refCon);
ci
Specifies the image decompressor component for the request.

data
Returns a pointer to the allocated memory.

dataSize
Specifies the desired size of the data buffer.

dataUse
A code that indicates how the memory is to be used. For example, the memory may be used to store compressed data before it's displayed, mask plane data, or decompressed data.

If there is no benefit to storing a particular kind of data in codec memory, the codec should refuse the request for the memory allocation. The defined values are for data use are:

0x00000001
Memory will be used for holding compressed image data.

0x00000002
Memory will be used for an offscreen image buffer.

memoryGoneProc
A pointer to a function that will be called before disposing of the memory allocated by a codec. Your callback function must be in the following form:

pascal void (*ICMMemoryDisposedProcPtr)
(Ptr memoryBlock, void *refcon);

This function must be called if the memory block is to be disposed of by the codec instead of by ImageCodeDisposeMemory . For example, this would occur if the codec is closed and still has memory allocation outstanding or if the memory is required to complete another operation. The memoryGoneProc must not be called at interrupt time.

refCon
Contains a reference constant value that your codec must pass to the memoryGoneProc function.

DISCUSSION

Your component receives the ImageCodecNewMemory request whenever an application calls the Image Compression Manager's CDSequenceNewMemory function (page 212) .

SPECIAL CONSIDERATIONS

The Image Compression Manager does not currently track memory allocations. When a compressor or decompressor component instance is closed, it must ensure that all blocks allocated by that instance are disposed (and call the ICMMemoryDisposeUPP ). If your codec does not currently have free memory for compression frame data, but will soon , you can return codecMemoryFullPleaseWait to indicate this fact.

ImageCodecNewImageBufferMemory

Requests the codec to allocate memory for an offscreen buffer of non-RGB pixels. This call is used to support a codec decompressing into a non-RGB buffer. The transfer codec is responsible for defining the offscreen and transferring the image from the offscreen to the destination.

pascal ComponentResult ImageCodecNewImageBufferMemory(
                     ComponentInstance ci,
                     CodecDecompressParams *params,
                     long flags,
                     ICMMemoryDisposedUPP memoryGoneProc,
                     void *refCon);
ci
Specifies the image decompressor component for the request.

params
Contains a pointer to a decompression parameters structure. See "The Decompression Parameters Structure" (Inside Macintosh: QuickTime Components, page 4-46), and "The Decompression Parameters Structure" in this chapter for a complete description. Your codec must fill in the dstPixMap.baseAddr and the dstPixMap.rowBytes fields in this structure.

flags
Currently, this parameter is always set to 0.

memoryGoneProc
A pointer to a function that will be called before disposing of the memory allocated by a codec. Your callback function must be in the following form:

pascal void (*ICMMemoryDisposedProcPtr)
(Ptr memoryBlock, void *refcon);

This function must be called if the memory block is to be disposed of by the codec instead of by ImageCodeDisposeMemory . For example, this would occur if the codec is closed and still has memory allocation outstanding or if the memory is required to complete another operation. The memoryGoneProc must not be called at interrupt time.

refCon
Contains a reference constant value that your codec must pass to the memoryGoneProc function.

DISCUSSION

Your component receives the ImageCodecNewImageBufferMemory request whenever another codec has requested a non-RGB offscreen buffer of the type of your component's subtype. See "Accelerated Video Support" for more information.

SPECIAL CONSIDERATIONS

The Image Compression Manager does not currently track memory allocations. When a compressor or decompressor component instance is closed, it must ensure that all blocks allocated by that instance are disposed (and call the ICMMemoryDisposeUPP ).

ImageCodecDisposeMemory

Disposes codec-allocated memory.

pascal ComponentResult ImageCodecDisposeMemory (
                     ComponentInstance ci,
                     Ptr data);
ci
Specifies the image compressor component for the request

data
Points to the previously allocated memory block.

DISCUSSION

Your component receives the ImageCodecDisposeMemory request whenever an application calls the Image Compression Manager's CDSequenceDisposeMemory function (page 214) .

SPECIAL CONSIDERATIONS

When a codec instance is closed, it must ensure that all blocks allocated by that instance are disposed (and call the ICMMemoryDisposeUPP ).

ImageCodecRequestSettings

Displays a dialog box containing codec-specific compression settings.

pascal ComponentResult ImageCodecRequestSettings (
                     ComponentInstance ci,
                     Handle settings,
                     Rect *rp,
                     ModalFilterUPP filterProc);
ci
Specifies the image compressor component for the request.

settings
A handle of data specific to the codec. If the handle is empty, the codec should use its default settings.

rp
A pointer to a rectangle giving the coordinates of the standard compression dialog box in global screen coordinates. The codec can use this to position its dialog box in the same area of the screen.

filterProc
A pointer to a modal dialog filter procedure that the codec must either pass to the ModalDialog function or call at the beginning of the codec dialog filter. This procedure gives the calling application and standard compression dialog box a chance to process update events.

DISCUSSION

The ImageCodecRequestSettings function allows the display of a dialog box of additional compression settings specific to the codec. These settings are stored in a settings handle. The codec can store any data in any format it wants in the settings handle and resize it accordingly. It should store some type of tag or version information that it can use to verify that the data belongs to the codec. The codec should not dispose of the handle.

ImageCodecGetSettings

Returns the settings chosen by the user.

pascal ComponentResult ImageCodecGetSettings (
                     ComponentInstance ci,
                     Handle settings);
ci
Specifies the image compressor component for the request.

settings
A handle that the codec should resize and fill in with the current internal settings. If there are no current internal settings, resize it to 0. Don't dispose of this handle.

DISCUSSION

The ImageCodecGetSettings function returns the codec's current internal settings. If there are no current settings or the settings are the same as the defaults, the codec can set the handle to nil .

ImageCodecSetSettings

Sets the settings of the optional dialog box.

pascal ComponentResult ImageCodecSetSettings (
                     ComponentInstance ci,
                     Handle settings);
ci
Specifies the image compressor component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

settings
A handle to internal settings originally returned by either ImageCodecRequestSettings or ImageCodecGetSettings . The codec should set its internal settings to match those of the settings handle. Because the codec does not own the handle, it should not dispose of it and should copy only its contents, not the handle itself. If the settings handle passed is empty, the codec should sets its internal settings to a default state.

DISCUSSION

The ImageCodecSetSettings function allows a codec to return its private settings. Set the codec's internal settings to the state specified in the settings handle. The codec should always check the validity of the contents of the handle so that invalid settings are not used.

ImageCodecHitTestData

This routine is called when the application calls PtInDSequenceData . It returns a Boolean indicating whether or not the specified point is contained within the specified image data.

pascal ComponentResult ImageCodecHitTestData(
                     ComponentInstance ci,
                     ImageDescriptionHandle desc,
                     void *data,
                     Size dataSize,
                     Point where,
                     Boolean *hit);
ci
Specifies the image decompressor component for the request.

desc
Contains an ImageDescriptionHandle for the image data pointed to by the data param.

data
Pointer to compressed data in the format specified by the desc param.

dataSize
Size of the compressed data referred to by the data param.

where
A QuickDraw Point (0,0) based at the top-left corner of the image.

hit
A pointer to a Boolean. The Boolean should be set to true if the point specified by the where parameter is contained within the compressed image data specified by the data param.

DISCUSSION

The ImageCodecHitTestData function allows the calling application to perform hit testing on compressed data. The codec should set the hit parameter to true if the compressed data contains data at the point specified by the where parameter. The hit parameter should be set to false if the specified point falls within a blank portion of the image.

ImageCodecGetMaxCompressionSizeWithSources

Your codec receives the request when an application calls the Image Compression Manager's GetCSequenceMaxCompressionSize function. The caller uses this function to determine the maximum size the data will be compressed to for a given image and set of data sources.

pascal ComponentResult ImageCodecGetMaxCompressionSizeWithSources(
                     ComponentInstance ci,
                     PixMapHandle src,
                     const Rect *srcRect,
                     short depth,
                     CodecQ quality,
                     CDSequenceDataSourcePtr sourceData,
                     long *size);
ci
Specifies the image decompressor component for the request.

src
Contains a handle to the source image. The source image is stored in a pixel map structure. Applications use the size information you return to allocate buffers for more than one image. Consequently, your compressor should not consider the contents of the image when determining the maximum compressed size. Rather, you should consider only the quality level, pixel depth, and image size.

This parameter may be set to nil . In this case the application has not supplied a source image--your component should use the other parameters to determine the characteristics of the image to be compressed.

srcRect
Contains a pointer to a rectangle defining the portion of the source image to compress.

depth
Specifies the depth at which the image is to be compressed. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.

quality
Specifies the desired compression image quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.

sourceData
Contains a pointer to a CDSequenceDataSource structure. This structure contains a linked list of all data sources. Because each data source contains a link to the next data source, a codec can access all data sources from this field.

size
Contains a pointer to a field to receive the maximum size, in bytes, of the compressed image.

DISCUSSION

The ImageCodecGetMaxCompressionSizeWithSources function is similar in purpose to the ImageCodecGetMaxCompressionSize function documented in Inside Macintosh: QuickTimeComponents (page 4-55). This function, however, also considers data sources that the codec may compress with the image.

ImageCodecSourceChanged

Your codec receives this notification that one of the data sources has changed when an application calls the Image Compression Manager's CDSequenceSetSourceData or CDSequenceChangedSourceData functions.

pascal ComponentResult ImageCodecSourceChanged(
                     ComponentInstance ci,
                     UInt32 majorSourceChangeSeed,
                     UInt32 minorSourceChangeSeed,
                     CDSequenceDataSourcePtr sourceData,
                     long *flagsOut);
ci
Specifies the image decompressor component for the request.

majorSourceChangeSeed
Contains an integer value that is incremented each time a data source is added or removed. This provides an easy way for a codec to know when it needs to redetermine which data source inputs are available.

minorSourceChangeSeed
Contains an integer value that is incremented each time a data source is added or removed, or the data contained in any of the data sources changes. This provides a way for a codec to know if the data available to it has changed.

sourceData
Contains a pointer to a CDSequenceDataSource structure. This structure contains a linked list of all data sources. Because each data source contains a link to the next data source, a codec can access all data sources from this field.

flagsOut
xx

DISCUSSION

This routine is provided to notify the codec component that one of the data sources has changed.

© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |